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31. Dates and Times 

The time: package contains a set of functions for manipulating dates and times: finding the 
current time, reading and printing dates and limes, converting between formats, and other 
miscellany regarding peculiarities of tlie calendar system. It also includes functions for accessing 
tlic Lisp Machine's microsecond timer. 

Times are represented in two different formats by tJie functions in the time package. One 
way is to represent a time by many numbers, indicating a year, a month, a date, an hour, a 
minute, and a second (plus, sometimes, a day of tlie week and timezone). The year is relative to 
1900 (that is, if it is 1983, tlie year value would be 83); however, tlie functions tliat take a year 
as an argument will accept either form, 'i^he month is 1 for January, 2 for February, etc. The 
date is 1 for the first day of a month. ITic hour is a number from_ to 23. The minute and 
second are numbers from to 59. Days of the week are fixnums, where means Monday, 1 
means 1 uesday, and so on. A timezone is specified as the number of hours west of GMT; thus 
in Massachusetts the timezone is 5. Any adjustment for daylight savings time is separate from 
this. 

This "decoded" format is convenient for printing out times into a readable notation, but it is 
inconvenient for programs to make sense of these numbers and pass them around as arguments 
(since there are so many of them). So there is a second representation, called Universal Time, 
which measures a time as the number of seconds since January 1, 1900, at midnight GMT. ITiis 
"encoded" format is easy to deal with inside programs, although it doesn't make much sense to 
look at (it looks like a huge integer). So both formats are provided; there are fbnctions to 
convert between the two formats; and many functions exist in two forms, one for each format. 

The Lisp Machine hardware includes a timer that counts once every microsecond. It is 
controlled by a crystal and so is fairly accurate. The absolute value of this timer doesn't mean 
anything useful, since it is initialized randomly; what you do with the timer is to read it at the 
beginning and end of an interval, and subtract the two values to get the length of the interval in 
microseconds. These relative times allow you to time intervals of up to an hour (32 bits) with 
microsecond accuracy. 

The Lisp Machine keeps track of the time of day by maintaining a "timebase", using the 
microsecond clock to count off the seconds. When the machine first comes up, the timebase is 
initialized by querying hosts on the Chaosnet to find out the current time. 

There is a similar timer that counts in 60ths of a second rather than microseconds; it is useful 
for measuring intervals of a few seconds or minutes with less accuracy. Periodic housekeeping 
fiinctions of the system are scheduled based on this timer. 
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31.1 Getting and Setting the Time 

time: get- time 

Get the current time, in decoded form. Return seconds, minutes, hours, date, month, 
year, day-of-the-week, and daylight-savings-time-p, with tlie same meanings as 
time:decode-universai-time (see page 633). 

time: get -universal -time 

Returns the current time in Universal Time form. 

time: set- local -time &optional new- lime 

Set tlie local time to tmv-time. If ne^v-time is supplied, it must be either a universal time 
or a suitable argument to time:parse (see page 631). If it is not supplied, or if there is 
an error parsing the argument, you will be prompted for tlie new time. Note that you 
will not normally need to call this fimction; it is useful mainly when the timebase gets 
screwed up for one reason or another. 

31.1.1 Elapsed Time in 60ths of a Second 

The following functions deal with a different kind of time. These are not calendrical 
date/times, but simply elapsed time in 60ths of a second. These times are used for many internal 
purposes where the idea is to measure a small interval accurately, not to depend on the time of 
day or day of month. 

time 

Returns a number that increases by 1 every 1/60 of a second. The value wraps around 
roughly once a day. Use the time-lessp and time-difference functions to avoid getting 
in trouble due to the wrap-around, time is completely incompatible with the Maclisp 
function of the same name. 

time-lessp timel time! 

t if limel is earlier than timel, compensating for wrap-around, otherwise nil. 

time-difference timel time2 

Assuming timel is later than timel, returns the number of 60ths of a second difference 
between them, compensating for wrap-around. 

time- increment time interval 

Increments time by interval, wrapping around if appropriate. 
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31.1.2 Elapsed Time in Microseconds 

time: microsecond- time 

Returns the value of tlie microsecond timer, as a bignum. The values returned by this 
function "wrap around" about once per hour. 

time rfixnum-microsecond- time 

Returns as a fixnum die value of the low 23 bits of die microsecond timer. Hiis is like 
time:microsecond-time, with die advantage diat it returns a value in die same format as 
die time flinction, except in microseconds radier than 60ths of a second. This means Uiat 
you can compare fixnum-microsecond-times with time-lessp and time -difference. 
time:fixnum- microsecond -time is also a bit faster, but has the disadvantage Uiat since 
you only see the low bits of die ckx:k, the value can "wrap around" more quickly (about 
every eight seconds). Note that die Lisp Machine garbage collector is so designed that the 
bignums produced by time:microsecond-time are garbage-collected quickly and efficiently, 
so die overhead for creating die bignums is really not high. 

31.2 Printing Dates and Times 

The functions in this section create printed representations of dmes and dates in various 
formats and send die characters to a stream. To any of these functions, you may pass nil as die 
stream parameter and die function will return a string containing the printed representation of die 
time, instead of printing the characters to any stream. 

time: print-current-time &optional (^/rram standard -output) 

Prints die current time, formatted as in 11/25/80 14:50:02, to the specified stream. 

time:print-time seconds minutes hours dale month year «feoptional 
{stream standard -output) 
Prints die specified time, formatted as in 11/25/80 14:50:02, to the specified stream. 

time: print-universal -time universal- time &optional (^/re^m standard -output) 
(timezone time: *timezone*) 
Prints die specified dme, formatted as in 11/25/80 14:50:02, to the specified stream. 

t1me:print-current-date &opdonal (5/reflm standard -output) 

Prints die current time, formatted as in Tuesday the twenty -fifth of November, 1980; 
3:50:41 pm, to the specified stream. 

time: print- date seconds minutes hours date month year day- of- the- week &optional 
{stream standard -output) 
Prints die specified dme, fomiatted as in Tuesday the twenty -fifth of November, 1980; 
3:50:41 pm, to die specified stream. 
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time:print-universal-date universal- lime &optional (5/rea/?? standard -output) 
(timezoneX\me:*\.\mezone*) 
Prints the specified time, formatted as in Tuesday the twenty-fifth of November, 1980; 
3:50:41 pm, to the specified stream. 

time:print-brief-universa1-time universal- time &optional (s/retzm standard -output) 
reference- time 
'fhis is like time:print- universal -time except tliat it omits seconds and only prints those 
parts of universal-time that differ from reference- time, a universal time tliat defaults to the 
current time. Thus the output will be in one of the following tliree forms: 
02:59 ; the same day 

3/414:01 ;a different day in the same year 

8/17/74 15:30 ; a different year 

31.3 Reading Dates and Times 

ITiese functions will accept most reasonable printed representations of date and time and 
convert them to the standard internal forms. TTie following are representative formats that are 
accepted by the parser. 

"March 15, 1960" "15 March i960" "3//i5//60" 

"15//3//60" "3//15//1960" "3-15-60" "15-3-1960" 

"3-15" "15-March-60" "15-Mar-60" "March-15-60" 

"1130." "11:30" "11:30:17" "11:30 pm" 

"11:30 AM" "1130" "113000" 

"11.30" "11.30.00" "11.3" "11 pm" "12 noon" 

^'midnight" "m" "Friday, March 15, 1980" "6:00 gmt" "3:00 pdt" 

"15 March 60" "15 march 60 seconds" 

"Fifteen March 60" "The Fifteenth of March, I960;" 

"One minute after March 3, 1960" 

"Two days after March 3, 1960" 

"Three minutes after 23:59:59 Dec 31, 1959" 

"Now" "Today" "Yesterday" "two days after tomorrow" 

"one day before yesterday" "the day after tomorrow" 

"five days ago" 

time: parse string &optional {start 0) (endnW) ifuturepi) base-time must-have-time 
date-must-have-year time-must-have- second (day-must-be-validt) 
Interpret string as a date and/or time, and return seconds, minutes, hours, date, month, 
year, day-of-the-week, daylight-savings-time-p, and relative-p. start and end delimit a 
substring of the string; if end is nil, the end of die string is used, must-have- time means 
that string must not be empty, date-musi-have-year means that a year must uC explicitly 
specified, time- must- have- second means that the second must be specified, daymust-be- 
valid means that if a day of the week is given, then it must actually be the day that 
corresponds to the date, base- time provides the defaults for unspecified components; if it 
is nil, the current time is used, futurep means that the time should be interpreted as 
being in the future; for exam.ple, if the base time is 5:00 and the string refers to the 
time 3:00, that means the next day if fiiturep is non-nil, but it means two hours ago if 
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fuiurep is nil. The relative-p returned value is t if the string included a relative part, such 
as "one minute after" or "two days before" or "tomorrow" or "now"; otherwise, it is nil. 

time: parse-universal-time siring &optional (smnO) (endnW) {futurepX) base-time 

musl-have-lime dale- must- have- year lime-musl-have- second {day-musl-he- validt) 
Ihis is the same as time:parse except that it returns one integer, representing tlic time in 
Universal Time, and the relaiive-p value. 

31.4 Reading and Printing Time Intervals 

In addition to the fimctions for reading and printing instants of time, there are other 
functions specifically for printing time intervals. A time interval is either a number (measured in 
seconds) or nil, meaning "never". The printed representations used look like "3 minutes 23 
seconds" for actual intervals, or "Never" for nil (some other synonyms and abbreviations for 
"never" arc accepted as input). 

time:print-interval-or-never interval &optional (s/rra//? standard -output) 

inter\^aJ should be a non-negative fixnum or nil. Its printed representation as a time 
interval is written onto stream. 

time: parse-interval -or-never string &optional start end 

Converts string, a printed representation for a time interval, into a number of nil. start 
and end may be used to specify a portion of string to be used; the default is to use all of 
string. It is an error if the contents of string do not look like a reasonable time interval. 
Here arc some examples of acceptable strings: 

"4 seconds" "4 sees" "4 s" 

"5 mins 23 sees" "5 m 23 s" "23 SECONDS 5 M" 

"3 yrs 1 week 1 hr 2 mins 1 sec" 

"never" "not ever" "no" "" 

Note that several abbreviations are understood, the components may be in any order, and 
case (upper versus lower) is ignored. Also, "montlis" are not recognized, since various 
months have different lengths and there is no way to know which month is being spoken 
of Ihis function will always accept anything that was produced by time:print-interval- 
or- never; fiirthemiore, it will return exactly the same fixnum (or nil) that was printed. 

time: read-interval-or-never &optional (s/rei7m standard -input) 

This fi.jnction reads a line of input from stream (using readline) and then calls 
time:parse-interval-or-never on the resulting string. 
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31.5 Time Conversions 

time :decode-uni versa! -time universal- lime &optional (//m<?zo//c time: *timezone*) 

Converts universal- lime into its decoded representation, llie following values are returned: 
seconds, m.iniitcs, hours, date, month, year, day-of-thc-wcck, daylight-savings-time-p. 
daylight savings- time- p tells you whether or not daylight savings time is in effect; if so, the 
value of hour has been adjusted accordingly. You can specify timezone explicitly if you 
want to know the equivalent representation for this time in other parts of the world. 

time :encode-uni versa! -time seconds minutes hours date month year &optional timezone 
Converts the decoded time into Universal Time fomiat, and return the Universal Time as 
an integer. If you don't specify timezone, it defaults to the current time/one adjusted for 
daylight savings time; if you provide it explicitly, it is not adjusted for daylight savings 
time, year may be absolute or relative to 1900 (that is, 81 and 1981 both work). 

time:*timezone* Variable 

The value of time:*timezone* is the time zone in which this Lisp Machine resides, 
expressed in terms of the number of hours west of GMT this time zone is. This value 
does not change to reflect daylight savings time; it tells you about standard time in your 
part of the world. 

31.6 Internal Functions 

These functions provide support for those listed above. Some user programs may need to call 
them directly, so they are documented here. 

time: initial ize-timebase 

Initialize the timebase by querying Chaosnet hosts to find out the current time. This is 
called automatically during system initialization. You may want to call it yourself to 
correct the time if it appears to be inaccurate or downright wrong. See also time:set- 
local-time, page 629. 

time : day! ight-savings-time-p hours date month year 

Return t if daylight savings time is in effect for the specified hour; otherwise, return nil. 
year may be absolute or relative to 1900 (that is, 83 and 1983 both work). 

time:dayl ight-savings-p 

Return t if daylight savings time is currently in effect; otherwise, return nil. 

time:month-length month year 

Return the number of days in the specified month', you must supply a year in case the 
month is February (which has a different length during leap years), year may be absolute 
or relative to 1900 (that is, 83 and 1983 both work). 



SRC:<L.MAN>TIME.TEXT.29 24-JAN-83 



Internal Functions 



634 



Lisp Machine Manual 



time: leap -year-p year 

Return t if year is a leap year; otherwise return nil. year may be absolute or relative to 
1900 (that is, 83 and 1983 both work). 

time: verify- date date month year day- of- the- week 

If the day of the week of the date specified by date, month, and year is the same as day- 
of-the-week, return nil; otherwise, return a string that contains a suitable error message. 
year may be absolute or relative to 1900 (that is, 83 and 1983 both work). 

time:day-of-the-week-stPing day- of- the- week &optional imode':\ong) 

Returns a string representing the day of the week. As usual, means Monday, 1 means 
Tuesday, and so on. Possible values of mode are: 

:long Returns tlie full English name, such as "Monday", "Tuesday", etc. This 

is the default. 

:short Returns a three-letter abbreviation, such as "Mon", "Tue", etc. 

:medium Same as :short, but use "Tues" and "Thurs". 

:french Returns the French name, such as "Lundi", "Mardl", etc. 

:german Returns the German name, such as "Montag", "Dienstag", etc. 

time: mo nth-string month &optional {mode '.lonQ) 

Returns a string representing the month of the year. As usual, 1 means January, 2 
means February, etc. Possible values of mode are: 

:long Returns the full English name, such as "January", "February", etc. 

This is the default. 

ishort Returns a three-letter abbreviation, such as "Jan", "Feb", etc. 

imedium Same as :short, but use "Sept", "Novem", and "Decem". 

:roman Returns the Roman numeral for month (this convention is used in 

Europe). 

ifrench Returns the French name, such as "Janvier", "Fevrier", etc. 

igerman Returns the German name, such as "Januar", "Februar", etc. 

time: timezone- string &optional (//w^zo«etime:*timezone*) 
(daylight-savifigs-p ({\me:6a.y\'iQhX-sa\/'mgs-p)) 
Return tlie three-letter abbreviation for this time zone. For example, if timezone is 5, 
then either "EST" (Eastern Standard Time) or "CDT" (Central Daylight Time) will be 
used, depending on daylight-savings-p. 
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